clsx

What is clsx?

The clsx package is a tiny utility for constructing className strings conditionally. It is also a faster & smaller drop-in replacement for the 'classnames' library.

What are clsx's main functionalities?

Conditional class string construction

This feature allows you to construct a class string with conditional classes. If the condition is true, the class is included; otherwise, it is excluded. In the code sample, 'baz' will be included in the output string, while 'qux-quux' will not, resulting in 'foo bar baz'.

clsx('foo', 'bar', { 'baz': true, 'qux-quux': false })

Combining class strings

clsx can combine multiple class strings and arrays of class strings, ignoring falsy values. In the code sample, the output would be 'foo bar baz qux'.

clsx('foo', null, ['bar', 'baz'], { 'qux': true })

Handling arrays and nested arrays

clsx can handle arrays and nested arrays of class names with conditional logic. In the code sample, the output would be 'foo bar baz' as the nested array and object are properly evaluated.

clsx(['foo', ['bar', { 'baz': true }]])

Other packages similar to clsx

classnames

The 'classnames' package is the original utility that clsx was designed to replace. It offers similar functionality for conditionally joining classNames together. clsx claims to be a faster and smaller alternative to 'classnames'.

emotion

The 'emotion' package is a performant and flexible CSS-in-JS library. While it is more feature-rich, offering styled components and dynamic styling, it also includes the 'cx' function which is similar to clsx for combining class names conditionally.

README

clsx

A tiny (228B) utility for constructing className strings conditionally.
Also serves as a faster & smaller drop-in replacement for the classnames module.

This module is available in three formats:

• ES Module: dist/clsx.m.js
• CommonJS: dist/clsx.js
• UMD: dist/clsx.min.js

Install

$ npm install --save clsx

Usage

import clsx from 'clsx';
// or
import { clsx } from 'clsx';

// Strings (variadic)
clsx('foo', true && 'bar', 'baz');
//=> 'foo bar baz'

// Objects
clsx({ foo:true, bar:false, baz:isTrue() });
//=> 'foo baz'

// Objects (variadic)
clsx({ foo:true }, { bar:false }, null, { '--foobar':'hello' });
//=> 'foo --foobar'

// Arrays
clsx(['foo', 0, false, 'bar']);
//=> 'foo bar'

// Arrays (variadic)
clsx(['foo'], ['', 0, false, 'bar'], [['baz', [['hello'], 'there']]]);
//=> 'foo bar baz hello there'

// Kitchen sink (with nesting)
clsx('foo', [1 && 'bar', { baz:false, bat:null }, ['hello', ['world']]], 'cya');
//=> 'foo bar hello world cya'

API

clsx(...input)

Returns: String

input

Type: Mixed

The clsx function can take any number of arguments, each of which can be an Object, Array, Boolean, or String.

Important: Any falsey values are discarded!
Standalone Boolean values are discarded as well.

clsx(true, false, '', null, undefined, 0, NaN);
//=> ''

Benchmarks

For snapshots of cross-browser results, check out the bench directory~!

Support

All versions of Node.js are supported.

All browsers that support Array.isArray are supported (IE9+).

Note: For IE8 support and older, please install clsx@1.0.x and beware of #17.

Related

• obj-str - A smaller (96B) and similiar utility that only works with Objects.

License

MIT © Luke Edwards